%% This file is part of Enblend.
%% Licence details can be found in the file COPYING.


\subsection[Expert Options]{\label{sec:expert-options}%
  \genidx[\rangebeginlocation]{expert options}%
  \genidx{options!expert}%
  Expert Options}% Not a \commonpart!


%%% IMPLEMENTATION NOTE: This file is included in both manuals, but
%%% rendered differently by conditional inclusion; Enblend and Enfuse
%%% have different sets of ``Expert Options''.  Hence, the name prefix
%%% `common-', but no `\commonpart' sign.


\ifenblend
  Control inner workings of \App{} and in particular the interpretation of images.
\fi

\ifenfuse
  Control inner workings of \App{} and the reading\slash writing of weight masks.
\fi


\begin{codelist}
  \label{opt:fallback-profile}%
  \optidx[\defininglocation]{--fallback-profile}%
  \genidx{profile!fallback}%
  \gensee{fallback profile}{profile, fallback}%
  \genidx{luminance interval!trivial}%
  \genidx{RGB-cube@\acronym{RGB}-cube}%
\item[--fallback-profile=\metavar{PROFILE-FILENAME}]\itemend
  Use the \acronym{ICC} profile in \metavar{PROFILE-FILENAME} instead of the default
  \acronym{sRGB}.  This option only is effective if the input images come \emph{without} color
  profiles \emph{and} blending is not performed in the trivial luminance interval or
  \acronym{RGB}-cube.

  Compare option~\flexipageref{\option{--blend-colorspace}}{opt:blend-colorspace} and
  \chapterName~\fullref{sec:color-profiles} on color profiles.


  \label{opt:layer-selector}%
  \optidx[\defininglocation]{--layer-selector}%
  \genidx{layer selection}%
\item[--layer-selector=\metavar{ALGORITHM}]\itemend
  Override the standard layer selector algorithm~\sample{\val{val:layer-selector}}.

  \App{} offers the following algorithms:

  \begin{codelist}
    \genidx{layer selection!all layers}%
  \item[all-layers]\itemend
    Select all layers in all images.

    \genidx{layer selection!first layer}%
  \item[first-layer]\itemend
    Select only first layer in each multi-layer image.  For single-layer images this is the same
    as \sample{all-layers}.

    \genidx{layer selection!last layer}
  \item[last-layer]\itemend
    Select only last layer in each multi-layer image.  For single-layer images this is the same
    as \sample{all-layers}.

    \genidx{layer selection!largest-layer}
  \item[largest-layer]\itemend
    Select largest layer in each multi-layer image, where the ``largeness'', this is the size is
    defined by the product of the layer width and its height.  The channel width of the layer is
    ignored.  For single-layer images this is the same as \sample{all-layers}.

    \genidx{layer selection!no layer}
  \item[no-layer]\itemend
    Do not select any layer in any image.

    This algorithm is useful to temporarily exclude some images in response files.
  \end{codelist}


\ifenfuse
  \label{opt:load-masks}%
  \optidx[\defininglocation]{--load-masks}%
  \genidx{mask!loading}%
  \gensee{load mask}{mask, loading}%
  \item[\itempar{--load-masks~\textrm{(\oldstylefirst~form)}
      \\ --load-masks=\metavar{SOFT-MASK-TEMPLATE}~\textrm{(\oldstylesecond~form)}
      \\ --load-masks=\metavar{SOFT-MASK-TEMPLATE}:\feasiblebreak
      \metavar{HARD-MASK-TEMPLATE}~\textrm{(\oldstylethird~form)}}]\itemend
    Load masks from images instead of computing them.

    The masks must be grayscale images.  All image formats understood by \App{} (see
    option~\flexipageref{\option{--show-image-formats}}{opt:show-image-formats}) are viable mask
    file formats, though those with floating-point pixels for example \acronym{TIFF} or
    \acronym{VIFF} are suited best.

    \genidx{mask!filename template}%
    \gensee{filename template}{mask, filename template}%
    \begin{sloppypar}
      \oldstylefirst~form: Load all soft-weight masks from files that were previously saved with
      option~\flexipageref{\option{--save-masks}}{opt:save-masks}.  \metavar{HARD-MASK-TEMPLATE}
      is effective only when loading hard masks (see
      option~\flexipageref{\option{--hard-mask}}{opt:hard-mask}).  The respective defaults are
      \mbox{\code{\val{val:default-soft-mask-template}}} and
      \mbox{\code{\val{val:default-hard-mask-template}}}.

      In the \oldstylesecond~form \metavar{SOFT\hyp{}MASK\hyp{}TEMPLATE} defines the names of
      the soft-mask files.

      In the \oldstylethird~form \metavar{HARD\hyp{}MASK\hyp{}TEMPLATE} additionally defines the
      names of the hard-mask files.  See
      option~\flexipageref{\option{--save-masks}}{opt:save-masks} below for the description of
      mask templates.
    \end{sloppypar}

    Options~\option{--load-masks} and~\option{--save-masks} are mutually exclusive.
\fi


  \label{opt:parameter}%
  \optidx[\defininglocation]{--parameter}%
\item[--parameter=\metavar{KEY}\optional{=\metavar{VALUE}}\optional{:\dots}]\itemend
  Set a \metavar{KEY}-\metavar{VALUE} pair, where \metavar{VALUE} is optional.  This option is
  cumulative.  Separate multiple pairs with the usual numeric delimiters.

  This option has the negated form \optidx[\defininglocation]{--no-parameter}%
  \sample{--no-parameter}, which takes one or more \metavar{KEY}s and removes them from the list
  of defined parameters.  The special key~\sample{*} deletes all parameters at once.

  Parameters enable the developers to change the internal workings of \App{} without the need to
  recompile or relink.

\begin{sgquote}
  \Author{\genidx{Jackson, Daniel@\propername{Jackson, Daniel}}Daniel Jackson: }%
  \Quote{I just hope we won't regret giving them those gate addresses.}

  \Author{\genidx{O'Neill, Jack@\propername{O'Neill, Jack}}Jack O'Neill: }%
  \Quote{I don't think we will, first one being a black hole and all.  They get progressively
    darker after that.}
\end{sgquote}


\ifenblend
    \label{opt:pre-assemble}%
    \optidx[\defininglocation]{--pre-assemble}%
    \shoptidx{-a}{--pre-assemble}%
    \genidx{preassemble}%
    \gensee{assemble}{preassemble}%
    \genidx{blending!sequential}%
    \gensee{sequential blending}{blending, sequential}%
  \item[\itempar{-a \\ --pre-assemble}]\itemend
    Pre-assemble non-overlapping images before each blending iteration.

    This overrides the default procedure, which is to blend the images sequentially in the order
    given on the command line.  \App{} will use fewer blending iterations, but it will do more
    work in each iteration.

    This option has the negated form \optidx[\defininglocation]{--no-pre-assemble}%
    \sample{--no-pre-assemble}, which restores the default.
\fi


  \label{opt:prefer-gpu}%
  \optidx[\defininglocation]{--prefer-gpu}%
  \genidx{OpenCL}%
  \genidx{OpenCL!device}%
  \genidx{OpenCL!platform}%
\item[--prefer-gpu=\optional{\metavar{PLATFORM}:}\metavar{DEVICE}
  \restrictednote{\acronym{OpenCL}-enabled versions only.}]\itemend
  Direct \App{} toward a particular \acronym{OpenCL} \metavar{DEVICE} on the first auto-detected
  \metavar{PLATFORM} or directly to the given \metavar{PLAT\shyp FORM}\slash\metavar{DE\shyp
    VICE} combination.  Use the numbers of platform and device found either with

  \begin{terminal}
    \$ \app{} --verbose --version
  \end{terminal}
  or
  \begin{terminal}
    \$ \app{} --show-gpu-info
  \end{terminal}

  Note that this option only selects \acronym{GPU}-devices; it does not \emph{activate} any, use
  option~\flexipageref{\option{--gpu}}{opt:gpu} for that.

  When told to employ the \acronym{GPU} with \sample{--gpu}, by default \App{} uses the first
  device on the first auto-detected platform it finds via queries of the \acronym{OpenCL}
  subsystem, where neither the device, nor the platform may be the ones the user wants.  Usually
  she will select the device with the highest performance, maximum possible number of
  work-items, and largest associated memory.


\ifenblend
    \label{opt:x}%
    \optidx[\defininglocation]{-x}%
    \genidx{result!checkpoint}%
    \genidx{checkpoint results}%
  \item[-x]
    Checkpoint partial results to the output file after each blending step.
\fi


\ifenfuse
    \label{opt:save-masks}%
    \optidx[\defininglocation]{--save-masks}%
    \genidx{mask!save}%
    \gensee{save mask}{mask, save}
  \item[\itempar{--save-masks~\textrm{(\oldstylefirst~form)}
      \\ --save-masks=\metavar{SOFT-MASK-TEMPLATE}~\textrm{(\oldstylesecond~form)}
      \\ --save-masks=\metavar{SOFT-MASK-TEMPLATE}:\feasiblebreak
      \metavar{HARD-MASK-TEMPLATE}~\textrm{(\oldstylethird~form)}}]\itemend
    Save the generated weight masks to image files.

    \genidx{mask!filename template}%
    \gensee{filename template}{mask, filename template}%
    \begin{sloppypar}
      \oldstylefirst~form: Save all soft-weight masks in files.  If
      option~\flexipageref{\option{--hard-mask}}{opt:hard-mask} is effective also save the hard
      masks.  The defaults are \code{\val{val:default-soft-mask-template}} and
      \code{\val{val:default-hard-mask-template}}.

      In the \oldstylesecond~form \metavar{SOFT\hyp{}MASK\hyp{}TEMPLATE} defines the names of
      the soft-mask files.

      In the \oldstylethird~form \metavar{HARD\hyp{}MASK\hyp{}TEMPLATE} additionally defines the
      names of the hard-mask files.
    \end{sloppypar}

    \genidx{save mask!only}%
    \gensee{only save mask}{save mask only}%
    \App{} will stop after saving all masks unless
    option~\flexipageref{\option{--output}}{opt:output} is given, too.  With both options given,
    this is, \sample{--save-masks} and \sample{--output}, \App{} saves all masks and then
    proceeds to fuse the output image.

    Both \metavar{SOFT\hyp{}MASK\hyp{}TEMPLATE} and \metavar{HARD\hyp{}MASK\hyp{}TEMPLATE}
    define templates that are expanded for each mask file.  In a template a percent sign
    (\sample{\%}) introduces a variable part.  All other characters are copied literally.
    Lowercase letters refer to the name of the respective input file, whereas uppercase ones
    refer to the name of the output file.  \tableName~\fullref{tab:mask-template-characters}
    lists all variables.

    A fancy mask filename template could look like
    \begin{literal}
      \%D/mask-\%02n-\%f.tif
    \end{literal}
    It puts the mask files into the same directory as the output file (\sample{\%D}), generates
    a two-digit index (\sample{\%02n}) to keep the mask files nicely sorted, and decorates the
    mask filename with the name of the associated input file (\sample{\%f}) for easy
    recognition.

    \genidx{mask!floating-point \acronym{TIFF}}%
    \gensee{floating-point \acronym{TIFF} mask}{mask, floating-point \acronym{TIFF}}%
    The masks carry the totaled images' weights.  They consist of single-channel, this is
    grayscale, floating-point data and thus preferably are saved in floating-point form.  \App{}
    defaults to floating-point~\acronym{TIFF}.

    Options~\option{--load-masks} and~\option{--save-masks} are mutually exclusive.
\fi
\end{codelist}


\ifenfuse
  \input{common-mask-template-characters}
\fi

\genidx[\rangeendlocation]{expert options}


%%% Local Variables:
%%% fill-column: 96
%%% End:
